<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->
<!-- $Id: overview.html 777748 2009-05-23 00:00:44Z sebb $ -->
<html>
   <head>
      <title>Overview of the com.frameworkset.commons.pool component</title>
   </head>
   <body>
      <p>
         Generic Object pooling API with several implementations.
      </p>
      <p>
         The <code>com.frameworkset.commons.pool</code> package defines a simple
         interface for a pool of object instances, and a handful of base
         classes that may be useful when creating pool implementations.
         The API supports pooling of unique objects which can be requested
         via a key as well as pools where all objects are equivalent.
      </p>
      <p>
         The <code>com.frameworkset.commons.pool.impl</code> package contains
         several pool implementations.
         {@link com.frameworkset.commons.pool.impl.StackObjectPool StackObjectPool}
         is useful for supporting reuse of a limited number of instances while
         allowing new instances to be created as needed to support high demand.
         {@link com.frameworkset.commons.pool.impl.GenericObjectPool
         GenericObjectPool} has many configuration options and can support
         a limited set of objects such as would be useful in a database
         connection pool.
         {@link com.frameworkset.commons.pool.impl.SoftReferenceObjectPool
         SoftReferenceObjectPool} has no limit on the number of objects in the
         pool, but the garbage collector can remove idle objects from the pool
         as needed.  There are also keyed versions of the first two.
      </p>
      <p>
         Here is a simple example of pooling <code>HashMap</code>'s. First
         create an {@link com.frameworkset.commons.pool.ObjectPoolFactory
         ObjectPoolFactory}
      </p>
<pre>
    public class HashMapFactory
        extends {@link com.frameworkset.commons.pool.BasePoolableObjectFactory BasePoolableObjectFactory}
    {
        /**
         * Creates an instance that can be returned by the pool.
         * @return an instance that can be returned by the pool.
         */
        public Object makeObject()
            throws Exception
        {
            return new HashMap();
        }

        /**
         * Uninitialize an instance to be returned to the pool.
         * @param obj the instance to be passivated
         */
        public void passivateObject(Object obj)
            throws Exception
        {
            Map map = (Map)obj;
            map.clear();
        }
    }
</pre>
      <p>
         A class that makes frequent use of a Map could then use a pool
         as shown below:
      </p>
<pre>
    public class Foo
    {
        private {@link com.frameworkset.commons.pool.ObjectPool ObjectPool} pool;
        public Foo()
        {
            {@link com.frameworkset.commons.pool.PoolableObjectFactory PoolableObjectFactory} factory = new HashMapFactory();
            pool = new StackObjectPool(factory, 1000);
        }

        public doSomething()
        {
            ...
            Map map = null;
            try
            {
                map = (Map)pool.borrowObject();
                // use map
                ...
            }
            finally
            {
                if (map != null)
                {
                    pool.returnObject(map);
                }
            }
            ...
        }
    }
</pre>

<p>
The above example shows how one would use an
{@link com.frameworkset.commons.pool.ObjectPool ObjectPool}.  The other supplied
implementations or another special purpose pool would be used similarly.
</p>
   </body>
</html>